Site Ranger is copyright 1998 by Thomas Reed (ThomasReed@kagi.com).
Site Ranger is a powerful web site manager for the Macintosh that can check all local links in your site, perform simple macro expansions, auto-correct links in moved files, and synchronize the web site with the mirror of the site on your hard drive.
The term macro expansions refers to the replacement of special codes you insert in your HTML files with expanded text that you supply. For example, if you have the following code at the end of your HTML file:
... <P>Here's the end of the file</P> <!--footer-->This is where the footer goes<!--/footer--> </BODY></HTML>
and you have a macro file, named "footer", containing the following HTML code:
<P><!--#fileName--> last modified <!--#modDate--> Central Standard Time (<!--#timeZone-->). This page copyright 1998 by <A HREF="mailto:ThomasReed@aol.com">Thomas Reed</A>.</P>
Site Ranger will modify your HTML file to look like this:
... <P>Here's the end of the file</P> <P>index.html last modified Thu, Apr 9, 1998 @ 8:22:08 AM Central Standard Time (-6GMT). This page copyright 1998 by <A HREF="mailto:ThomasReed@kagi.com">Thomas Reed</A>.</P> </BODY></HTML>
Notice that the macro expansions are powerful enough that you can insert certain pre-defined codes (such as file name or modification date codes) within your macros, and they will be expanded dynamically.
Site Ranger requires a Macintosh computer running version 7.0 or later of the Mac OS system software.
Installation is easy -- simply put the application anywhere you want it to go!
Site Ranger is $20 shareware. You may use it free of charge for a 30-day period to evaluate it. After that time, you must register it. You may register using the Register application that came with the Site Ranger package. For instructions or detailed pricing information, see the "How To Register" document.
Site Ranger may be redistributed only under the following conditions:
Anyone wishing to redistribute Site Ranger may e-mail me to be placed on a list to receive update notifications.
Please support shareware! It is only through your support that Site Ranger can continue to improve!
Site Ranger assumes that you are using a "mirrored" approach to your web site design. This means that you have a "mirror", or copy, of all the files on your web site in a folder on your hard drive, and that all the files within that folder are organized in EXACTLY the same way as the files on the web server. If you do not have such a folder, you will need to create one. (The easiest way may be to download your entire site to your hard drive.) Note that if you need help with this concept, or with other concepts about file interactions in HTML, you should read the first chapter of The Pixel Pen.
To create a new site (assuming the site folder on your hard drive already exists), choose New Site from the File menu. You will be asked where to save the site file, and then to select a site folder. You may save the site file anywhere -- even inside the site folder. The site file will remember where your site folder is even if you move it around.
Once you have created or opened a site file, you will see a window that contains a list of all the files in the site. You can use this window to move or copy files in the same manner as in the Finder.
Site settings can be changed by selecting Site Settings from the Site menu when you have a site file open. There are three panes to the Site Settings dialog, which may be accessed by choosing the desired pane from the pop-up menu at the top of the dialog.
This pane contains two check boxes with which you may specify what to do during a build. The Check Links check box tells Site Ranger to check the links in your site after performing the macro expansion portion of the build. The Synchronize Site check box tells Site Ranger to synchronize the site as the last portion of the build (ie, after the macro expansion and, if requested, the link check).
Note that these options are only default values -- at each build, Site Ranger prompts you for these options again. You may choose different options at that time, and the options you choose will take effect for that build only.
This pane allows you to set the needed information to connect with your web server via FTP. This information is required for site synchronization.
The host name field is the address of your server -- for example, "www.mysite.com" or "123.456.78.90". Some servers require that you use a different address for FTP access than for access over the web, so talk to your provider if you're not sure where to connect to. Note that you should not include the "ftp://" or "http://" prefix placed on URLs.
The path field is the path to your file space on the server. If you run your own server, this can be blank, but for most people this will look something like "~myusername/" or "/~myusername/". If you're not sure whether to include the initial '/', try connecting manually with an FTP client first to see what works. The trailing '/' should always be present.
The user name field is simple -- just the username for logging in. If you don't know this, you're in trouble!
The password field is also simple, it just stores your password for logging in. However, if security is a concern, you can leave this field blank and Site Ranger will prompt you for a password at each site synchronization.
Note that if you are unable to get Site Ranger to connect, you need to be sure that you're able to connect manually using the selected FTP client. If you can connect manually, but not with Site Ranger, please contact me for help. If you cannot connect manually, I won't be able to help -- you'll need to talk to your service provider to find out why.
The Site Info pane lets you set a few pieces of data about your site that help in the way Site Ranger handles URLs in your files when checking or correcting them.
The Base site URL field allows you to specify an absolute URL that represents the location of the root folder of your site (this may NOT be the same as the root folder of the server). For example, my web site's root is at "http://home.earthlink.net/~thomasareed/". All files within that directory are mirrored in the site folder on my hard drive. Note that you should NOT specify a file name in the URL you enter, and you should include the trailing '/'!
The Default file name field allows you to set the default URL used by your site. For most sites, this is "index.html" or "index.htm", though some may use other names such as "default.html". When you set this field, Site Ranger treats a URL such as "pages/" as if it read "pages/XXX", where XXX is the default file name you entered.
This pane allows you to select the FTP client (either Anarchie or Fetch) to use with site synchronizations. Select the desired client from the indicated pop-up menu.
To check the links in a site, choose Check Links from the Site menu with a site file open. It will check the links contained in every HTML file in the site window. If any invalid links are found, you may correct them by locating the file or manually typing in the correct address. If the link you enter is still not correct, Site Ranger will continue to ask that you fix the link until it is either correct or until you tell it to do otherwise.
Site Ranger will also check the anchor contained in each link (if any) and verify that it is correct. If it is not, Site Ranger will ask that you correct the anchor as well.
You may also select a group of files and folders and choose Check Selection. This will check the links only in the selected files. (If you select a folder, all contained files will be checked.)
For info on how Site Ranger handles different types of URLs, see the How URLs are handled section.
Building a site performs macro expansions as described for each file modified since the last build. Optionally, it may do two other things as well: 1) check the links on all files in the site to ensure inserted macro text is correct, and 2) synchronize the files on the web server with the files in the site folder on your hard drive.
To build a site, you must first set up the macros. To do so, follow these steps:
For more details on macros and their capabilities, see the reference section.
To begin building, choose Build Site from the Site menu. Site Ranger will examine every HTML file in your site and build those that have changed since the last build.
You can also choose to use the Build Selection item, which will build only those files/folders that are currently selected. Note that there are several BIG differences between Build Site and Build Selection! First, Build Selection forces the build of all selected items, regardless of modification dates. (This means that a folder selected will have ALL its contents built.) Second, link checking and site synchronization are not done after the build is complete. Build Selection is meant to be used in such ways as to try out changes on a specific file or group of files, and should not be used to build an entire site!
You may choose at the time of build whether to check links and synchronize the web server.
Site synchronization is part of the build process, but is important enough that it deserves separate mention. Synchronization involves uploading of new or changed files and deletion of removed files on the server. For example, if you remove a file "cheesewhiz.html" from the site folder on your local hard drive, that file will also be removed from the web server at the next build (assuming site synchronization is requested).
There is really nothing special you have to do to synchronize your site except to provide server access information -- the address of the server, path to your storage space, and your username and password. You specify these items in the Site Access Info pane of the Site Settings dialog. (Note that you may leave the password blank in shared environments for security -- Site Ranger will then prompt you for a password at each synchronization.)
The other thing you must do is be sure to have either Anarchie or Fetch on your computer, and select the one you wish to use for site synchronizations in the FTP Client pane of the Site Settings dialog. Site Ranger performs all FTP functions by way of an FTP client. One important note: Fetch does not return errors to Site Ranger when something goes wrong -- so you may get strange behavior if your server is down, if you specify incorrect values in the Site Access Info pane of the site settings, or if other error conditions occur. If you have such behavior, check the Fetch Transcript window in Fetch to see what went wrong.
Ordinarily, any files that have been modified since the last build (or any files that are modified by the build process itself by having macros inserted) are the files that are eventually uploaded. However, at times, you may wish to avoid uploading some files. To do this, simply select the file or files to be excluded and choose Mark Selection Uploaded from the Site menu. This will prevent those files from being uploaded, and will also prevent macro expansion in any selected HTML files from occurring, the next time you build the site. Note, however, that the next time you modify any of the selected files, they will be re-uploaded at the next build. Also note that if you change a macro file affecting one of the marked files, it will be built and uploaded anyway. This option is meant solely as a means to prevent the upload of files that already exist in identical form on the server.
You should always use Site Ranger's site window to move, copy, rename or delete files in your site. Using the Finder to make these changes prevents Site Ranger from compensating for the changes.
Moving and copying files is easy -- the file list displayed in each site window works just like the Finder. You can drag files and folders to move them, or hold down the option key while dragging to copy them. Renaming also works as in the Finder, by simply clicking on the file name (or selecting the file and pressing Return) and waiting until the name becomes editable.
When you perform any of these operations, Site Ranger will automatically fix any links that may have become broken by the change. The details of how the links are fixed can be found in the reference section below.
Deleting is done by either moving the file outside the site folder or choosing Delete File from the Site menu. Note that when a file is deleted, nothing is done to links in or to that file. This will be changed in future versions.
For info on how Site Ranger handles different types of URLs, see the How URLs are handled section.
Site Ranger itself is not yet scriptable, though it will be. However, you can place AppleScript files in the (macros) folder to have scripts generate macro text.
Scripted macros are actually very easy -- if you're familiar with AppleScript. If you're not interested in AppleScript programming, I've included a few sample AppleScripts you can use in the Goodies folder. They can also help you learn how to write scripted macros.
To write a scripted macro, use Apple's Script Editor (or your favorite third-party script editor) to create a new script. The new script should be made to look like this:
on <<event SRmcMcro>> fileParam ... end <<event SRmcMcro>>
(Note that the '<<' and '>>' characters are not actually two less-than or greater-than symbols as shown here. Instead, they are single characters generated by typing option-\ or shift-option-\.)
The code within this "on" block will be run by Site Ranger when it needs data to insert in an HTML file. The fileParam parameter will be an alias to the file in which the data will be inserted. Have your code inside the "on" block do whatever you wish, as long as it ultimately returns a text string containing the HTML code to insert.
Here's an example of a script that will return the full path of the file in which the macro will be inserted:
on <<event SRmcMcro>> fileParam tell application "Finder" return fileParam as text end tell end <<event SRmcMcro>>
The resulting macro, if it were generated by a macro script named "test", might look like:
<!--test-->HD:Web:Site A:index.html<!--/test-->
For more examples, see the Goodies folder.
This section does not duplicate info found in the Getting Started section. For that reason, be sure to read Getting Started before reading this section.
Site Ranger can recognize relative URLs, absolute URLs that lie within the site, root-based URLs, and URLs in files with a base document URL.
Relative URLs are treated simply -- the file is located according to the URL relative to the containing file.
Absolute URLs are only recognized by Site Ranger if they lie within the site folder. Site Ranger decides which URLs point to files within the site folder by comparing the URL to the base site URL specified in the Site Info pane of the Site Settings dialog. For example, if the base site URL is "http://www.mysite.com/~abc/", a URL "http://www.mysite.com/~abc/pages/index.html" will be recognized. Examples of URLs that would not be recognized are "http://www.mysite.com/~xyz/index.html" or "http://www.somesite.com/".
Root-based URLs, which start with an initial '/' character, may or may not be recognized. Such a URL is relative to the server root, which is not neccessarily the same as the site root. For example, if you use the URL "/index.html" on a site where the base site URL (as specified in the Site Info pane of the Site Settings dialog) is "http://www.mysite.com/~abc/", the indicated file is at "http://www.mysite.com/index.html". In this case, a root-based URL is not recognized. However, if your site folder root represents the server root, such URLs are handled.
Some documents may contain a base document URL, specified with a <BASE HREF="..."> tag in the HTML header. Any links inside such a document will be handled from that base location (with the exception of absolute or root-based URLs).
URLs are located by searching for HREF, SRC, or BACKGROUND attributes in any tag. URLs found outside such attributes -- for example, in the text of a page -- will be ignored. The value of these attributes does not need to be quoted, although HTML 4.0 standards technically require quotes for URL attribute values -- call this "error handling". Unquoted attribute values may contain only alphanumeric characters or the characters in the set "#%-./:_~" (quotes not included) -- any other character will be considered the end of the attribute value. This is WAY more than HTML 4.0 requirements, so if this breaks on your pages, you should add quotes around attribute values.
URLs that fall within the scope of your site are currently the only links checked. See the How URLs are handled section for the definition of what URLs are considered in your site.
Note that links in macro files are checked, under the assumption that all links in macro files are relative to the containing macro file. See the Macros section below for details.
The macro codes inserted in the HTML files take the form of HTML comments made to work similarly to HTML tags. Since they are comments, you can leave them there without interfering with the normal display of your web site. Browsers will simply ignore them. One thing you will need to think about, though, is whether there are any special codes defined by your editor that work the same way. Claris Home Page, for example, defines a <!--noedit-->...<!--/noedit--> set of comments that allow you to tell it not to edit a block of HTML code. If your editor does something similar, you will want to make sure not to use anything reserved by your editor as a macro name (such as "noedit" in the case of Claris Home Page).
Note that currently, a macro cannot contain other macros. In other words, codes for other macros placed within a macro file will not be expanded. If there is sufficient demand for such capabilities, I may add this capability.
Links may be placed inside macro files, and will be automatically corrected for each file the macro is inserted in, but must follow one simple rule -- they MUST be made relative to the containing macro file. That is, the links must be able to work from within the macro file if the macro file were a full-fledged HTML file. For example, if your site was in the folder "HD:web:mysite:", and you were building a link to a file at "HD:web:mysite:a:test.html", you would use the URL "../a/test.html". (Remember that macro files are always inside a sub-folder called "(macros)", thus the initial "../" in the URL.)
A macro can contain any of several special codes that will insert custom information. These codes are of the form <!--#code-->. Note that they DO NOT use a closing code, and that they may only appear within macro text. If such a code appears inside a web page file, it will be ignored.
The special codes available are as follows:
When you move or rename a file, Site Ranger will automatically fix all links to the old location that are recognized as lying within the site to point to the new location. You may move as many files or folders as you like, and links to all of them will be fixed. Also, links within the moved files will be fixed, as they may have become invalid.
Copying works similarly, except that only links within the new copies are modified. Links to the copies that are found within the copied files will be modified to point to the new location. Links to the copied files that are found elsewhere in the site are left alone. So you may copy files freely without worrying that all the links in your site will be changed to point to the location of the copy rather than the original.
Choosing Delete File simply moves the selected file(s) into the Trash without doing anything to links in or to the deleted file(s). You can achieve the same effect by dragging files out of the site window onto the Trash icon on your desktop. The files are not actually deleted from the hard drive until you empty the trash.
As with many other modern applications, Site Ranger allows you to drag files to other applications, such as the Finder. However, note that if a move or copy occurs as a result of such a drag, the links will not be changed. Therefore, you should only move and copy files within your site by dragging from one location in your site window to another if you want auto-correction to occur.
Note that links inside your macro files will be properly auto-corrected, assuming they follow the rules for links in macro files. See the Macros section for details.
Certain files and folders, such as the macro folder, are hidden from many Site Ranger operations. These files or folders (including the files they contain) are not displayed in the file list, are not searched for macros to expand, and are not uploaded to the web site. And all that's involved in hiding an item is enclosing its name in parentheses, just like for the "(macros)" folder.
When checking links or auto-correcting links for moved files, hidden folders are treated a little differently. Site Ranger will actually look at files inside of hidden folders for these operations. The reason for this is so that links inside files in the (macros) folder can be checked or fixed. Similarly, a good use for a hidden folder would be to store HTML code to be used by a scripted macro, and so Site Ranger can check this code as well. If you wish for a file to be skipped during these operations, enclose its name in parentheses -- not just the name of the enclosing folder. (Note that non-text files will not be touched during such operations no matter where they are, so you don't need to do anything special with them.)